home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software Vault: The Gold Collection
/
Software Vault - The Gold Collection (American Databankers) (1993).ISO
/
cdr36
/
gapcdr6.zip
/
GAPCDR.TXT
< prev
next >
Wrap
Text File
|
1993-04-19
|
161KB
|
5,284 lines
GAP Communications Online Software
GAPCDR
Door Interface Library
Copyright (C) 1987-1993 by GAP Development Company.
ALL RIGHTS RESERVED. No part of this manual shall be reproduced,
stored in a retrieval system, or transmitted by any means,
electronic, mechanical, photocopying, recording, or otherwise,
without written permission from GAP Development Company. While
every precaution has been taken in the preparation of this
manual, GAP Development Company assumes no responsibility for
errors or omissions. Neither is any liability assumed for damages
resulting from the use of the information contained herein.
GAPCDR is the sole and exclusive property of GAP Development
Company. It is licensed and not sold to the end user with
restrictions placed upon its use.
GAPCDR is copyrighted by GAP Development Company.
DESQview is a trademark of Quarterdeck.
PCBoard is a trademark of Clark Development Corporation.
WildCat! is copyrighted by Mustang Software.
DigiBoard is a trademark of DigiBoard Incorporated.
Contents
Description 5
Major Features 5
Getting Started 7
Supported Compilers 8
Using GAPCDR 8
Points To Remember 11
Compiling And Linking 12
Using A Goto 13
BBS System Files 14
Sysop Setup And Functions 14
Configuration 15
Sysop Functions 17
Advanced Applications 18
Communications 18
DOS Window 20
Variables 22
Defines 22
Ansi Variables 22
DOOR.SYS Variables 23
Global Variables 25
Functions - Quick Reference 27
Functions - Detailed Reference 28
Index 81
Page 3
Page 4
GAP Communications GAPCDR
Description Description
GAPCDR is a professional development kit for Bulletin Board Door
programmers. Written in Microsoft C version 7 and MASM version 6,
it is fast, reliable, easy to use, and easy to incorporate into
the serious programmer's source code. It consists of a set of C
and assembler library routines to allow for easy door programming
and interfacing. Borland C compatability is included.
Major Features Major Features
Interfaces with GAP Communications, PCBoard, WildCat, and
other fine BBS programs that are capable of writing a
DOOR.SYS file.
Full communications support including the DigiBoard COM/Xi
series of Intelligent Multi-Port boards.
Supports the FIFO buffers of the 16550 UART chip.
Speeds up to 115,200 baud.
Communications ports other than Com 1 and Com 2 possible.
Supports CTS/RTS, automatically.
Does not require watchdog or CTTY.
Fully self contained, built in ANSI driver.
Sysop sees what the caller sees.
High speed text file display.
Supports ANSI color and ASCII text files with no
programming effort other than to make a single function
call.
Easy to use Random Number Generator.
Informative Status Line display.
Monitors keyboard activity and caller time remaining.
Page 5
GAP Communications GAPCDR
Easy interface to BBS system.
Sysop chat with full word wrapping.
Allows the sysop to shell to DOS.
"Remembers" the default drive and directory which prevents
file access errors.
Credits caller with time spent chatting or while sysop is
in a DOS shell.
Sysop can twit caller without caller ever knowing the sysop
is watching.
Caller time can be increased or decreased.
Full programmer control of whether or not to update the BBS
system files.
Time calculations are not dependent on the "seconds since
midnight" and are thus unsusceptible to the midnight roll
over.
Timer routines are hardware independent.
Automatic detection of multi-user system.
Input routines are consistent throughout the program.
Uses the latest in Microsoft C and MASM features.
Extremely easy interfacing to door programs.
Fully DESQView aware video routines as well as keyboard and
COM input routines, and COM output routines.
GAPCDR includes robust Communications routines which are fully
interrupt driven. Written in highly optimized assembler, they are
capable of operating at any speed which the UART on an IBM type
of computer is capable of producing. The FIFO buffers in the
16550 UART are fully supported. CTS/RTS checking is automatic,
and carrier detect is an integral part of each of the
communications input and output routines. When there is a loss of
carrier, a function in the main GAPCDR code will be called. This
Page 6
GAP Communications GAPCDR
function defaults to shutting down the door and returning to the
BBS, however you may modify it to do whatever you wish.
The built in ANSI driver makes GAPCDR a self contained unit. The
driver is smart enough to know when a caller does not want ANSI
sequences sent to his computer and it will filter out any such
codes that pass through it. This allows you to create prompts
with embedded ANSI sequences and display them without regard as
to whether or not the caller has color "turned on". This also
means you do not have to keep two sets of prompts (one with color
attributes and one without). This is a great savings to you in
precious DATA space. You may also use the ANSI driver to send
color strings to the local monitor. Even if the caller is in mono
mode, you may still send color strings and prompts to the ANSI
driver and have them displayed in color on the local monitor.
GAPCDR supports only the DOOR.SYS format for passing caller
information to a door. We choose this format because of its
universal acceptance and its inherent ability to remain stable.
BBS programs frequently change and with those changes usually
come modifications to the system files they create to interact
with door programs. DOOR.SYS on the other hand was designed to
include as much information about a caller as was thought
necessary. Should new fields be needed to take care of new BBS
features, it is a simple matter to add these new fields to the
end of the file, thereby making the new version compatible with
all prior versions. Most major BBS programs support DOOR.SYS.
Getting Started Getting Started
GAPCDR is distributed in archived format. The contents of the
archive should be as follows:
GAPCDR.TXT - Disk based documentation.
GAPCDRS.LIB - Small model Library routines.
GAPCDRL.LIB - Large model Library routines.
GAPCDRBS.LIB - Small model Library routines for BC.
GAPCDRBL.LIB - Large model Library routines for BC.
GAPCDR.H - Door Interface include file.
GAPSTRUC.H - Door Interface include file.
CDOOR.ZIP - Sample program illustrating many of the
features of GAPCDR.
READ.ME - Any pertinent information which you
should read.
Page 7
GAP Communications GAPCDR
If you licensed the source code to GAPCDR you will receive most
of the ASM, C, INC, H, BAT, and OBJ files that make up the GAPCDR
library. We include both Microsoft and Borland batch files to
compile the source modules.
Supported Compilers Supported Compilers
We used the Microsoft C compiler version 7.0, the Borland C++
Compiler version 3.0, and MASM version 6. The linker and
librarian were from their respective compilers.
Since GAPCDR uses no floating point math, the C modules were
compiled with the /FPa switch for Microsoft. This is the default
for Borland, so no switches are necessary. For Microsoft C, in
order to use the /FPa switch, you must tell the SETUP program
that you want to create the Alternate Floating Point library. It
will then create a set of libraries that make calls to the
Alternate Math library instead of the Emulator Library. The
difference in code size for a large model program that uses the
Alternate library as opposed to the Emulator library is typically
around 10k. Even if you do not use floating point arithmetic in
your program, the Math Library will still be linked in because it
contains the routines to do long arithmetic. So, the smaller the
library, the smaller your programs!
Place the GAPCDR files in your work directory. You may place the
LIB files in the MSC\LIB or BORLAND\LIB directory.
The text editor you use must allow control characters to be
entered and displayed. The ANSI variables are initialized with
literal characters and if your editor removes the ESC character
from the strings, your ANSI displays will be quite messy.
Using GAPCDR Using GAPCDR
At the very beginning of your program, you must include the
GAPCDR.H file. Without this file, nothing will work. It is
normally included after the C header files that your program may
need. To include the file, you type the following after including
the regular C header files:
#include "gapcdr.h"
GAPCDR.H contains the declarations for the external global
variables. In addition, it includes GAPSTRUC.H which contains the
structure declarations and the function prototypes.
Page 8
GAP Communications GAPCDR
Note: Any of your source modules that include GAPCDR.H
must have an include declaration for STDIO.H prior to
including GAPCDR.H. It should be standard practice to
include STDIO.H in your source modules anyway, so this
shouldn't present any problems.
The first thing that must be done prior to using any of the door
functions, is to initialize GAPCDR itself. This is accomplished
by making a call to read_cnf. Read_cnf opens the configuration
file (the name of which you pass as a parameter on the door
command line) and reads the first eight lines of the file. If the
configuration file cannot be found, the program will end. The
format of the configuration file is as follows:
c:\gap
The Crow's Nest
0
0
STANDARD
D000
320
4
The first line of the file is the path to the BBS default
directory. The second line is the name of the BBS. The third line
is the Port IRQ and the 4th line is the Port Base Address. If the
sysop running your program has his BBS configured to use Com
Ports other than 1 or 2, he would then enter the IRQ and Base
address for his Com Port on lines 3 and 4. GAPCDR derives the
Port Number from the DOOR.SYS file.
Lines five through eight are for the Intelligent DigiBoard multi-
port Communications Card. The DigiBoard routines specifically
support the COM/Xi series. All four of these lines are required
even if your end users are using the Standard Interface. Line
five is the Communications Port Interface. It must be one of the
following:
STANDARD DIGIBOARD INT14/EBIOS
The Standard interface is the one that will normally be used. If
an end user is using a DigiBoard then either the DigiBoard or
Int14/EBIOS interface may be selected. Most sysops will use the
Int14/EBIOS interface. All input/output to the DigiBoard is
performed via Interrupt 14 calls and a Device Driver (available
Page 9
GAP Communications GAPCDR
from DigiBoard) handles the interface between the program and the
board. The DigiBoard interface uses Direct Programming. GAPCDR
talks to the board directly without the need for a Device Driver.
In order to use this interface, a program called RESETDIG.EXE
must be used in the AUTOEXEC.BAT file to reset the DigiBoard once
when the computer is first booted. If the end user does not have
this program (it is a part of the GAP Communications BBS package)
then the Int14/EBIOS interface must be used.
If the Interface is other than STANDARD, then lines 6 through 8
will be ignored. If the Interface is INT14/EBIOS, then lines 6
and 7 will be ignored.
Line 6 is the DigiBoard Memory Window, or the address the board
uses as a communications area between itself and the Host
Computer. This line is used only if the Interface is set to
DIGIBOARD. It can be set to 0 if the Interface is STANDARD or
INT14/EBIOS.
Line 7 is the DigiBoard I/O Port Address. This line is used only
if the Interface is set to DIGIBOARD and can be set to 0
otherwise.
Line 8 is the DigiBoard Channel Number. This line is required for
the DIGIBOARD and INT14/EBIOS Interfaces. It is normally 1 - 8
for the DIGIBOARD Interface and 4 - 11 for the INT14/EBIOS
Interface. The Channel Number is similar to a Port Number. It
tells the program which of the DigiBoard Communications ports to
use.
The configuration file is usually given a name similar to the
name of your door program, with a CNF extension. Read_cnf will
leave this file open for your use. If you have any configuration
options of your own, you may place them in this file beginning
with line 9. Do not read your configuration options until after
making a call to init_door (which should be the second function
call in your program). Upon return from init_door, you are free
to read your configuration options (if any). At this time, you
should close the configuration file.
Normally, your program is invoked with a command line parameter
giving the name of the configuration file to use:
DOOR DOOR.CNF
You would use the argv parameter to your main function to extract
the configuration parameter and then pass this parameter on to
read_cnf. This allows the end user to use a single program (your
Page 10
GAP Communications GAPCDR
program) with multiple configuration files. This is especially
important under multi-user systems where separate configuration
files are needed.
The configuration file is opened as a stream, so using fgets or
any of the stream input functions would be appropriate for
reading the data. Remember that the file pointer is passed back
to you after the call to read_cnf. An example of the first few
"door" statements that might appear in a source file would be:
FILE *cnf_file; // pointer to config file
cnf_file = read_cnf(argv[1]); // read the cnf file
init_door(); // init the door
fclose(cnf_file); // close the cnf file
If there were no errors, read_cnf will return. You must now make
a call to init_door. Init_door uses the information derived from
line 1 of the configuration file to open and read DOOR.SYS. In
addition, init_door opens the communications port (if a remote
user is on), initializes some global variables, initializes the
random number generator, initializes the ANSI driver, and
installs a Ctrl-Break handler. If there is an error, init_door
will not return. Instead it will end the program.
That is basically all you have to do to initialize the GAPCDR
module. When your program ends, you should clean house if
necessary and call leave. Leave closes the communications port
and any open files, restores the ISR routines to their original
state, sends a sign off message to the caller, and then exits to
DOS. It is of vital importance to exit the door by making a call
to leave. Failure to do so will leave communication interrupts
active and the ctrl-break intercept active. The vectors to these
routines will be left in the interrupt vector table and the
computer will surely lock up the first time any program is run.
Points To Remember
To get the ball rolling, include GAPCDR.H after the C
header files.
To initialize the door, call read_cnf with the name of your
program's configuration file. Then call init_door.
Call leave when your program is finished.
Page 11
GAP Communications GAPCDR
All input and output should be performed through the GAPCDR
functions. The sample program gives good examples on how to
accomplish this. If you use the C runtime output routines
such as printf or cputs, the local screen will be a mess
because the internal ANSI driver will not know where the
cursor is.
To determine if the BBS is a single or multi user system,
check the variable called multi. If it is anything other
than 0, then the BBS is multi-user and you should
read/write your data files with sharing attributes.
Do not use any of the BBS specific functions such as
read_pcbsys or read_gapuser unless you know that your
program is running with the appropriate BBS system. You may
want to use a flag in your configuration file to determine
which system your program is running with. These functions
were provided to make your programming choores easier but
using them basically restricts your door to the respective
BBS system that the functions interact with.
To test your program, you will need a DOOR.SYS file that
was written for local exit. Of course, you can always
modify any DOOR.SYS file and change the first line so that
it reads COM0:. A complete set of sample files are provided
for testing your program under local mode.
Compiling And Linking Compiling And Linking
GAPCDR has already been compiled with the necessary compile time
switches for both Microsoft C and Borland C.
To compile your programs, use whatever switches are required for
your compiler.
Microsoft C
cl /c /FPa door.c
link door,,NUL.MAP,+GAPCDRx
Borland C
bcc -c door.c
tlink c0x+door,door.exe,NUL.MAP,+GAPCDRBx+Cx
Page 12
GAP Communications GAPCDR
Where door is the name of your program and 'x' is 'S' for the
small model library or 'L' for the large model library.
As was mentioned previously, GAPCDR was compiled with the /FPa
option for Microsoft C. The /FPa option produces smaller
executable files.
If you licensed the source code to GAPCDR, there are suplementary
files to aid in re-compiling and librarying the source modules.
GAPCDR has not been tested with Quick C, although there is no
reason why it should not work with the QC environment.
GAPCDR uses the PASCAL function calling convention. If you are
unfamiliar with this calling convention it means that the
parameters to a function are pushed onto the stack from left to
right instead of right to left. In addition, the function being
called is responsible for removing arguments from the stack. In
the C calling convention, the function making the call is
responsible for restoring the stack. What this means is if you
make 10 calls to show_mess, there will be 10 instances where the
stack must be restored upon return from the function. In the
PASCAL convention, there will be only one instance where this
will occur and it will be in show_mess just prior to the actual
return. The end result of using the PASCAL calling convention is
smaller code size.
It should be noted that the PASCAL convention cannot be used with
functions that take a variable number of arguments. In addition,
using the PASCAL convention absolutely requires that all
functions be prototyped. Otherwise the compiler will generate
redeclaration errors and the linker will generate unresolved
external reference errors.
Using A Goto Using A Goto
A word about using goto. If you licensed the source code to
GAPCDR, you will find that we use the goto in several places. It
should be pointed out that speed and compactness, combined with
readability, are our number one concerns. We performed several
experiments with the goto. We took a very simple function that
consisted of a while loop and a few statements embodied within
the loop. We took the same function and rewrote it using a
counter variable and a goto and removed the while loop. The
assembler output and resultant object code was 1/2 the size as
that of the function that used the while loop.
Page 13
GAP Communications GAPCDR
We are not proposing that anyone give up the fine structure of C
and use gotos as a beginning programmer in Basic might do. In
fact, if you are a beginning programmer in C, you should avoid
using gotos altogether until you become more proficient.
BBS System Files BBS System Files
Since we are firm believers that the BBS system files belong to
the BBS and should not be altered by any door program, updating
the BBS system file is not automatic. If you wish that any
decrease or increase in the user's time (kept track of in the
timecredit variable), be made permanent, you may, after
initializing the door, call the function that opens the system
file. For PCB, this would be PCBOARD.SYS. Keep track of any time
credits during the door programs operation, then call the
function that updates the BBS system file. For GAP, you would
need to re-write DOOR.SYS with any updated information.
Sysop Setup And Functions Sysop Setup And Functions
These sysop setup and function descriptions should be placed in
the documentation of your door program. You should, of course,
change the setup information to fit your particular needs.
Door programs written with the GAPCDR Door Interface Module will
run on any BBS system that is capable of writing a DOOR.SYS file.
For GAP Communications and WildCat, you need do nothing special
when configuring your doors. These programs will write a DOOR.SYS
file automatically. For PCBoard, you must explicitly tell the
Door File editor to write a DOOR.SYS file, when setting up a
GAPCDR door program.
Page 14
GAP Communications GAPCDR
Configuration Configuration
To configure the door for a particular BBS setup, a configuration
file must be used. At the very minimum, this file will contain
eight lines. It may contain more than eight depending upon a
particular door's configuration requirements. The name of the
file is usually the same as that of the door program but with a
CNF extension. The minimum requirements for the file are as
follows:
c:\gap
The Crow's Nest BBS
IRQ
Port Address
Interface
DigiBoard Window
DigiBoard I/O Address
DigiBoard Channel Number
The first line is the full path to your BBS default directory.
For GAP, this is usually C:\GAP. For PCB, this is usually C:\PCB.
The second line is the name of your BBS. The third line is the
IRQ that should be used for the port, and the fourth line is the
Base Port Address. If you are just using Com 1 and Com 2, you may
enter a 0 on these two lines.
Lines five through eight are for the Intelligent DigiBoard multi-
port Communications Card. The DigiBoard routines specifically
support the COM/Xi series. All four of these lines are required
even if you are using the Standard Interface. Line five is the
Communications Port Interface. It must be one of the following:
STANDARD DIGIBOARD INT14/EBIOS
The Standard interface is the one that will normally be used. If
you are using a DigiBoard then either the DigiBoard or
Int14/EBIOS interface may be selected. Most sysops will use the
Int14/EBIOS interface. All input/output to the DigiBoard is
performed via Interrupt 14 calls and a Device Driver (available
from DigiBoard) handles the interface between the program and the
board. The DigiBoard interface uses Direct Programming. GAPCDR
talks to the board directly without the need for a Device Driver.
In order to use this interface, a program called RESETDIG.EXE
must be used in the AUTOEXEC.BAT file to reset the DigiBoard once
when the computer is first booted. If you do not have this
program (it is a part of the GAP Communications BBS package) then
the Int14/EBIOS interface must be used.
Page 15
GAP Communications GAPCDR
If the Interface is other than STANDARD, then lines 6 through 8
will be ignored. If the Interface is INT14/EBIOS, then lines 6
and 7 will be ignored.
Line 6 is the DigiBoard Memory Window, or the address the board
uses as a communications area between itself and the Host
Computer. This line is used only if the Interface is set to
DIGIBOARD. It can be set to 0 if the Interface is STANDARD or
INT14/EBIOS.
Line 7 is the DigiBoard I/O Port Address. This line is used only
if the Interface is set to DIGIBOARD and can be set to 0
otherwise.
Line 8 is the DigiBoard Channel Number. This line is required for
the DIGIBOARD and INT14/EBIOS Interfaces. It is normally 1 - 8
for the DIGIBOARD Interface and 4 - 11 for the INT14/EBIOS
Interface. The Channel Number is similar to a Port Number. It
tells the program which of the DigiBoard Communications ports to
use.
GAPCDR will obtain the sysop's name from the DOOR.SYS file.
You must now create a batch file to invoke the door. This batch
file is placed in the directory where you told your BBS SetUp
program to look for it. Such a batch file might look like this:
@echo off
cd \gap\doors\tourist
tourist tourist.cnf
cd \gap
As you can see, the door is invoked by passing the configuration
file name as the first parameter.
You will also need to modify your doors menu files and the data
file that tells the BBS what your doors are and the security
level needed to access them. For GAP, these are respectively:
DOORM
DOORMG
DOORS.DAT
If you are running multi-nodes, simply create a separate door
configuration file for each node, and number them. For instance,
Page 16
GAP Communications GAPCDR
for a 3 node system, you might have the following configuration
files:
TOURIST1.CNF
TOURIST2.CNF
TOURIST3.CNF
The only difference between the three would be the 1st line which
points to the default directory for the particular node.
Multi-user operation is automatic.The DOOR.SYS file contains a
field that specifies if the BBS is multi-user or not.
Sysop Functions Sysop Functions
The following sysop functions are available while awaiting
keyboard input :
F5 - Shell to DOS.
F8 - Twit user and return to BBS.
F10 - Initiate chat with user.
CF10 - Answer user page bell.
Home - Main user stats.
End - Displays sysop keys available.
PgDn - Secondary user stats.
Up Arrow - Increase user's time remaining.
Dn Arrow - Decrease user's time remaining.
One of the nicer features about using the TWIT key, is the user
is not told that "the sysop wants them to return to the BBS".
Instead, a very plain and simple message of "returning you to the
BBS" is displayed. This way, the user is given no indication that
the sysop is hovering about.
When using the F5 shell to DOS key, to return to the door
program, simply type EXIT at the DOS command prompt. It is not
necessary to change directories back to the door directory.
GAPCDR is smart enough to know which drive and directory the door
program is in and will reset the defaults upon return from DOS.
In addition, the status line will remain on the screen.
It should be noted that when in a DOS shell, the GAPCDR status
line is protected by intercepting BIOS video calls. If you use
ANSI.SYS replacements which write directly to the video, you will
not have this protection and your status line will scroll off the
screen
Page 17
GAP Communications GAPCDR
The Up and Down Arrow keys increase and decrease the user's time
respectively by 5 minutes for each press of the key. There is no
indication of what is occurring (except by the fact the user's
time remaining will change), so the sysop should try not to have
a lead finger. The increase or decrease is effective only while
the user is in the door. Whether or not these time credits (plus
or minus) are made a permanent part of the user record so that
upon return from the DOOR, the BBS program will recognize them,
depends upon the door author.
Advanced Applications Advanced Applications
GAPCDR includes a great many advanced functions which can be used
with or without the BBS Door Interface (i.e., automatic status
line, time left checking, keyboard timeout checking, etc).
Communications Communications
The communications functions are an integral part of GAPCDR and
are called automatically by an output routine if the variable
local is set to 0. However, they may be used stand alone or
called directly if necessary. These routines are fully self-
contained with the exception of 3 global variables and 3 external
functions.
The global variables are:
baud - Port speed
gotdv - Flag signalling the presense of DESQview
port - Communications Port Number
The external functions are:
no_carrier - Called if carrier is dropped
timer - Time delay routine
dv_pause - Called to give up time slice
Before using the communications routines as stand alone
functions, you should make a call to dv_here so that it can set
the gotdv flag. If you are not concerned about the presense of
DESQview, you must declare this variable and initialize it to 0:
Page 18
GAP Communications GAPCDR
short near gotdv = 0;
Note that it must be declared such that it resides in the default
data segment. If you declare the variable yourself, you must
insure that the DESQVIEW.ASM module is not linked in to your
program. You will need to create a dummy function called dv_pause
that does nothing but return. This is necessary because even if
you do not wish to use the dv_pause function, the linker will
complain if it cannot find it:
void _pascal dv_pause(void);
Next, you must set the variable port to the port number you will
be using. Ports start at 0, where COM 1 equals Port 0. Then set
the variable baud to the bps rate you want the port opened at.
Your program will need to include a function called no_carrier.
It is prototyped as:
void _pascal no_carrier(void);
This function is called by the communications routines when they
detect that there is no carrier. You may do whatever you wish
inside this function but keep in mind that it will continue to be
called if there is no carrier on the port. You most certainly do
not want to make calls to any of the communications functions
from inside this routine or a stack overflow will eventually
result. If you wish to do your own carrier detecting (as you
would if you were going to be using these functions to create a
dial out type of program), then this function can simply contain
a return.
Once you have the global variables configured, the first step in
initializing the serial port is to make a call to setport.
Setport creates the receive buffer and then sets up the serial
port. After the port is configured, you should then call
init_port to set the baud, parity, and data bits. Init_port
supports all the baud rates that a UART on an IBM type of
computer is capable of utilizing. After this the port is fully
configured and may now be utilized. Before your program ends, you
must call reset_port to restore the interrupt vector back the way
it was.
The main input routines are:
comgetc - Get a single character from the port
comgetd - Get a character with timeout
Page 19
GAP Communications GAPCDR
The main output routines are:
computc - Send a single character
computs - Send a string
There are routines for checking carrier, turning DTR on and off,
checking if there are any characters in the receive buffer, and
clearing the receive buffer.
If you need to change baud rates simple set the variable baud to
whatever bps rate you want to change to and then call init_port.
DOS Window DOS Window
GAPCDR includes some very advanced functions for setting up what
we call a DOS Window. This is a Window that you define on the
local screen and to which all DOS output will be redirected. For
instance, if you needed to shell to DOS to run PKUNZIP or DSZ,
you could set up a DOS Window and all output from these two
programs will be contained inside the window. The window can also
be used without shelling to DOS although there is really no
practical use for doing so.
To set up a DOS window, the first thing you should do is make a
call to get_attr so that the current screen colors can be stored
away. This is necessary because you may want to use special
colors in your DOS window. By storing the original screen
attributes, they can be restored when you close the window,
thereby keeping the user's screen colors the way the user likes
them!
At the beginning of your program call get_attr. Do this before
you do any screen output. You will then make several calls to the
various GAPCDR functions to setup your DOS window. Once it is
configured, you can then shell to DOS and do whatever you like.
All screen output will take place inside the window. Please note
that if you use a console driver other than CON or ANSI.SYS (and
this generally includes all so called video speed up programs),
or run a program that writes directly to the screen, then output
will not take place inside of the window. This is because video
speed up programs generally write directly to the screen instead
of using the BIOS.
To see how the DOS window works, after setting it up, issue the
following call:
Page 20
GAP Communications GAPCDR
system("COMMAND");
This will put you in a DOS shell. You may then execute various
DOS functions and get a feel for what it looks like. Be sure to
type "exit" to return to your program.
When you no longer need the DOS window, it is imperitive that you
remove the interrupt 10 (BIOS) intercepter or your computer will
hang when you exit the program.
There is a fully working example of a DOS Window in the CDOOR
example program. It shows how to save a portion of the screen,
draw a box, set up the interrupt 10 intercepter and shell to DOS.
Upon return from the shell, it will remove the DOS Window.
Page 21
GAP Communications GAPCDR
Variables Variables
Defines Defines
The following defines are used when calling show_mess.
NO - Defined as 0
YES - Defined as 1
Ansi Variables Ansi Variables
ANSI strings contain the actual ANSI color sequences.
A_BLACK - ANSI codes for Black
A_BLUE - ANSI codes for Blue
A_BROWN - ANSI codes for Brown
A_CYAN - ANSI codes for Cyan
A_GREEN - ANSI codes for Green
A_MAGENTA - ANSI codes for Magenta
A_RED - ANSI codes for Red
A_WHITE - ANSI codes for White
A_BBLACK - ANSI codes for Grey
A_BBLUE - ANSI codes for bright Blue
A_BCYAN - ANSI codes for bright Cyan
A_BGREEN - ANSI codes for bright Green
A_BMAGENTA - ANSI codes for bright Magenta
A_BRED - ANSI codes for bright Red
A_BWHITE - ANSI codes for bright White
A_YELLOW - ANSI codes for Yellow
Page 22
GAP Communications GAPCDR
DOOR.SYS Variables DOOR.SYS Variables
DOOR.SYS variables are initialized while reading the DOOR.SYS
file. These variables are the door programmer's connection to the
BBS.
Short Integers Short Integers
alarm - 0 = caller alarm off, 1 = on
baud - DTE bps rate (unsigned)
bell - 0 = page bell off, 1 = bell on
color - 0 = no color, 1 = color
curfiles - current files downloaded
dflt_color - BBS default color
digiseg - DigiBoard Memory Window
digiport - DigiBoard I/O Port
digichnl - DigiBoard Channel #
expert - 0 = novice, 1 = expert
interface - 0 = Standard, 1 = DigiBoard, 2 = INT14/EBIOS
level - user's security level
local - 0 = remote user, 1 = local user
maxfiles - max files available
minsleft - minutes left at door start
multi - 1 = system is multi-user
node - node number in use, 0 = single
page - page length
parity - actually data bits, not used
port - com port being used
printer - 0 = printer off, 1 = printer on
realcredit - time credits from the BBS
screen - 0 = screen off, 1 = screen on
userbaud - remote user's bps rate (unsigned)
Page 23
GAP Communications GAPCDR
Long Integers Long Integers
curbytes - current download bytes
doors_open - total doors opened
downbytes - total download bytes
downloads - total number of downloads
maxbytes - max bytes can download
mesleft - total messages left
recnum - user's record number
timeson - # of times on
upbytes - total upload bytes
uploads - total number of uploads
Character Arrays Character Arrays
bphone - user's business phone number
city - user's home town
event_time - event run time
fname - user's first name
handle - caller's Handle
hphone - user's home phone number
last_new - last new files scan
lastdate - last date user was on
lname - user's last name
password - user's password
subscrip - date user's subscription expires
username - user's full name
Page 24
GAP Communications GAPCDR
Global Variables Global Variables
These variables are the documented, global variables (initialized
and used by GAPCDR). They may be modified and/or used at the
programmer's discretion.
Characters Characters
chat - true if chatting with user
clockon - 0 no clock, 1 display clock
column - column we are at now
endview - true if dont want to viewany more
flag - flag that a space was pressed
instatus - if doing status line
noup - if 1, dont uppercase characters
NS - true if in Non Stop mode
redisplay - true if wants to start over
usemore1 - true if showing a file
view - true to use the more prompt
wordwrap - column to wrap words at
Short Integers Short Integers
base_add - base address for port
irq - IRQ for port
lines - # of lines currently displayed
normal - current display color
timecredit - any time credits user may have
timeleft - time user has left
Long Integers Long Integers
starttime - time door opened
temptime - for calculating time out
timenow - current time
Page 25
GAP Communications GAPCDR
Character Arrays Character Arrays
anystring - global garbage collector
bbs_dir - path to DOOR.SYS
birthday - caller's birth date
board_name - name of the BBS
BS - backspace characters
CRLF - carriage return/line feed characters
curtime - holds the current time as a string
gendir - path to the BBS gen dir
maindir - path to the BBS main dir
strtime - holds the time string
sysname - sysop's name
Structures Structures
GAP_USER user - GAP's User Record
PCBSYS pcbsys - PCB's System Record
PCBUSER pcbuser - PCB's User Record
These structures are fully commented in the GAPCDR.H header file.
Note that when utilizing the GAP user structure, all string
fields are fully padded with spaces and the last position must be
a 0.
Page 26
GAP Communications GAPCDR
Functions - Quick Reference Functions - Quick Reference
access1 - Checks for the existence of a file.
ansi - Displays ANSI color strings.
backspace - Sends one or more backspaces.
ckeypress - Checks for a remote or local key press.
clear_scrn - Clears the local and remote screens.
clr_buf - Cleare the communications receive buffer.
cls - Clears the 1st 23 lines on the local screen.
cls_all - Clears the entire local screen.
comgetc - Gets a character from com port.
comgetd - Geta a character from com port with timeout.
computb - Sends a buffer of data to com port.
computc - Sends a character to com port.
computs - Sends a string to com port.
cursoff - Turns local cursor off.
curson - Turns local cursor on.
do_chat - To allow sysop to chat with remote user.
dtr - Toggels the DTR line on or off.
dv_here - Checks for the presense of DESQView.
dv_pause - Gives up remainder of time slice to DV.
elap_time - Computes elapsed time.
empty - Empties a string.
fix_color - Modifies ANSI driver for color or mono.
gapputc - Sends a character to local and remote.
gapputs - Sends a string to local and remote screens.
getakey - Gets one key responses.
getkeyc - Gets keyboard character and scan code.
get_attr - Gets startup video attribute.
get_random - Returns a random number.
get_string - Gets a string of characters.
init_ansi - Initializes ANSI driver.
init_com - Initializes Communications Port.
init_door - Initializes the Door.
init_port - Sets up Communications Port.
iscd - Checks if there is a Carrier.
leave - Shuts down door and returns to the BBS.
lputc - Sends a character to local screen.
lputs - Sends a string to local screen.
make_sound - Makes noise on local computer.
more - Checks for a full screen.
nl - Sends a CR/LF to local and remote.
no_carrier - Called by the Comm Routines if Carrier lost.
pagesysop - Alerts sysop that the user wants to chat.
pause - Sends a "Press [Any Key] To Continue" prompt.
putkey - Used by chat for word wrapping.
read_cnf - Reads the door configuration file.
Page 27
GAP Communications GAPCDR
read_doorsys - Reads DOOR.SYS.
read_gapuser - Reads USERS.DAT.
read_pcbsys - Reads PCBOARD.SYS.
read_pcbuser - Reads PCB USERS file.
read_score - Reads and displays top 10 scores.
reset_port - Restores Communications Port.
restore_screen - Restores a portion of the screen.
rest_cbreak - Restores Ctrl-Break vector.
rest_int10 - Restores BIOS vector.
rts - Toggels RTS line on or off.
rxempty - Checks if any characters in receive buffer.
save_screen - Saves a portion of the screen.
setport - Initializes Communications port.
set_attr - Sets video attributes.
set_cbreak - Initializes Ctrl-Break vector.
set_cord - Sets up a DOS Window.
set_int10 - Initializes BIOS trapper.
set_status - Displays status line.
show_file - Displays text files.
show_mess - Displays a message.
timer - Time Delay.
time_credit - Gives credits for time used.
time_left - Computes time remaining.
trim - Trims spaces from string.
update_clock - Updates status line clock.
wrap_word - Wraps a word.
write_gapuser - Writes USERS.DAT.
write_pcbsys - Writes PCBOARD.SYS.
write_pcbuser - Writes PCB USERS.
write_score - Creates and maintains top 10 scores file.
Functions - Detailed Reference Functions - Detailed Reference
Functions will return either a void (nothing), a short value, or
a character pointer.
The function descriptions will note whether or not a function is
high level or low level. The high level functions are basically
the only functions you will ever need to use. When necessary,
they will call other functions to carry out their work. The low
level functions, on the other hand, are more single purpose, and
they generally require calls to other low level functions to
perform the same task as one call to a high level function.
Page 28
GAP Communications GAPCDR
access1
-----------------------------------------------------------------
Purpose Checks for the existence of a file.
short access1(char *filename);
filename Full path and name of file
Type High Level
Description This function is used to check for the existence of
a file. It works in a multi-user environment and is
not affected by file sharing attributes.
Return Value 0 = File exists, 1 = File not found.
Example
if ((access1("FILE.DAT")))
show_mess("Sorry, File does not Exist!", YES,YES);
ansi
-----------------------------------------------------------------
Purpose Displays ANSI color sequences.
void ansi(char *color);
color Ansi color string
Type High Level
Description This function will send a string of ANSI escape
sequences to the remote user and to the local
console. The ANSI codes for the various colors are
declared as global variables. If the remote or
local user is in non graphics mode, the function
returns immediately.
Return Value None.
Example ansi(A_BWHITE); // Change color to bright white
Page 29
GAP Communications GAPCDR
backspace
-----------------------------------------------------------------
Purpose Sends one or more backspaces.
void backspace(short num);
num Number of backspaces to send
Type High Level
Description In order to actually erase a character on the
screen, you must send a 3 character sequence which
consists of backspace, space, backspace. This
function will send as many of these 3 character
sequences as you specify in the parameter list.
Return Value None.
Example backspace(1); // erase last character sent
ckeypress
-----------------------------------------------------------------
Purpose Checks for a remote or local key press.
short ckeypress(void);
Type High Level
Description This function will check the local keyboard as well
as the communications receive buffer to see if a
key is waiting to be read. It is most often used in
loops that monitor keyboard timeout, time
remaining, etc.
Return Value 0 = no key is waiting, 1 = a key is waiting.
Example c = ckeypress(); // key pressed?
while(!ckeypress()) // do nothing
{ // until a key is pressed
dv_pause() // give up time slice
}
Page 30
GAP Communications GAPCDR
clear_scrn
-----------------------------------------------------------------
Purpose Clears local and remote screens.
void clear_scrn(void);
Type High Level
Description This routine will use the assembler routine cls to
clear the first 23 lines of the local screen. If
the remote caller is in non-color mode, it sends a
CTRL-L to the remote screen, otherwise it sends the
ANSI clear screen sequence.
Return Value None.
Example clear_scrn(); // clear screen
clr_buf
-----------------------------------------------------------------
Purpose Clears the Communications receive buffer.
void clr_buf(void);
Type Low Level
Description Empties the receive buffer such that any pending
characters are simply ignored.
Return Value None.
Example clr_buf(); // clear the receive buffer
Page 31
GAP Communications GAPCDR
cls
-----------------------------------------------------------------
Purpose Clears the first 23 lines on the local screen.
void cls(void);
Type Low Level
Description This function will clear the first 23 lines on the
local screen, thereby protecting the bottom 2
lines.
Return Value None.
Example cls(); // clear 1st 23 lines
cls_all
-----------------------------------------------------------------
Purpose Clears the entire local screen.
void cls_all(void);
Type Low Level
Description This function will clear the entire local screen.
It is used by leave to tidy up the screen.
Return Value None.
Example cls_all(); // clear entire screen
Page 32
GAP Communications GAPCDR
comgetc
-----------------------------------------------------------------
Purpose Retrieve a character from communications buffer.
short comgetc(void);
Type Low Level
Description Checks the communications receive buffer and
returns the next character, if any.
Return Value Next character in buffer or -1 for no characters to
read.
Example c = comgetc(); // get a character from remote
comgetd
-----------------------------------------------------------------
Purpose Retrieve a character from comminications buffer
with delay.
short comgetd(short secs);
secs Number of seconds to wait
Type Low level
Description This function is the same as comgetc, except that
if there are no characters in the receive buffer,
it will wait for the number of seconds you specify.
Comgetd is fully DESQview aware and will give up
the program's time slice while waiting for incoming
characters.
Return Value Next character in buffer or -10 for time-out (no
characters to read).
Example
if ( (comgetd(2)) == -10) // wait for 2 seconds
; // nothing happening
Page 33
GAP Communications GAPCDR
computb
-----------------------------------------------------------------
Purpose Sends a buffer of data out the communications port.
void computb(char *buffer,short len);
buffer Buffer containing data to send
len Number of bytes to send
Type Low Level
Descripton This function will send a user suplied buffer of
len bytes out the communications port, one byte at
a time. It will not return until all characters
have been sent.
Return Value None.
Example computb(buffer,100); // Send 100 bytes of data
computc
-----------------------------------------------------------------
Purpose Sends a single character out the communications
port.
void computc(unsigned char ch);
ch Character to send
Type Low Level
Description Will send a single character out the communications
port.
Return Value None.
Example computc('A'); // Send a character
Page 34
GAP Communications GAPCDR
computs
-----------------------------------------------------------------
Purpose Sends a string of characters out the communications
port.
void computs(char *str);
str String to send
Type Low Level
Description Will send a string of characters out the
communications port. Note that unlike computb, the
number of bytes to send is determined by the length
of the string. Therefore this function stops
sending characters when it encounters the null
byte.
Return Value None.
Example computs("Send this string"); // send a string
cursoff
-----------------------------------------------------------------
Purpose Turns the local cursor off.
void cursoff(void);
Type Low Level
Description This function is used to turn the cursor on the
local monitor off.
Return Value None.
Example cursoff(); // turn the cursor off
Page 35
GAP Communications GAPCDR
curson
-----------------------------------------------------------------
Purpose Turns the local cursor on.
void curson(void);
Type Low Level
Description This function is used to turn the cursor on the
local monitor on.
Return Value None.
Example curson(); // turn the cursor on
Page 36
GAP Communications GAPCDR
do_chat
-----------------------------------------------------------------
Purpose To allow sysop to chat with remote user.
void do_chat(void);
Type High Level
Description This function allows a one on one chat with a re-
mote user. If the caller is in graphics mode, the
sysop's key presses will be displayed in green and
the remote user's key presses will be displayed in
white. Text will automatically wrap at column 76.
To exit chat, press either the ESC key or type a
CTRL-X. Note that the user may also send these
characters to end chat. The user will receive full
credit for the time spent chatting with the sysop.
However, this function will not update the BBS
system file so it is possible that the user may be
logged off (with an out of time message) when
he/she returns to the BBS.
Return Value None.
Example do_chat(); // chat with caller
empty(response,1); // initialize string
get_string(response); // get a string
if (response[0] == 'P') // paging sysop
do_chat(); // chat with sysop
Page 37
GAP Communications GAPCDR
dtr
-----------------------------------------------------------------
Purpose Toggle the DTR line on and off.
void dtr(short how)
how 0 = Turn DTR off.
1 = Turn DTR on
Type Low Level
Description This routine is used to turn the DTR line of the
communications port on or off. Turning DTR off
while there is a carrier will cause the modem to
drop carrier on the remote caller. In order to send
commands to the modem, DTR needs to be on.
Return Value None.
Example
dtr(1); // turn DTR on
computs("ATZ"); // reset the modem
Page 38
GAP Communications GAPCDR
dv_here
-----------------------------------------------------------------
Purpose Checks to see if the program is running under
DESQview.
short dv_here(void);
Type Low Level
Description This function should generally be called when a
program first starts (before any screen output is
performed). It makes a special DOS call to see if
DESQview is installed. If so, it sets an internal
flag indicating the presense of DV. If the program
is detected to be running under DESQview then all
"do nothing" loops (those loops that are looking
for something to do but because they are waiting
for keyboard or com input, are basically taking up
computer time doing nothing), will give up the
remainder of their time slice after they figure out
there is nothing for them to do. In addition,
because the built in ANSI driver writes directly to
the screen, if DESQview is present, the driver will
instead write to DV's video shadow buffer. This
function is automatically called by init_door so it
is not necessary to call it again.
Return Value DESQview version number or 0 for not installed.
Example
if ( (dv_here()))
show_mess("We are running under DESQview!", NO,YES);
Page 39
GAP Communications GAPCDR
dv_pause
-----------------------------------------------------------------
Purpose Give up remainder of time slice to DESQview.
void dv_pause(void);
Type Low Level
Description If DESQview is installed, this function will make a
call to DV such that DV will immediately switch to
another task. Note that dv_here must be called at
the beginning of the program since it sets an
internal variable that this function checks to see
if DESQview is running.
You should use this function inside of all "do
nothing" loops.
Return Value None.
Example
time (&temptime); // start timer
while (!getakey()) // until a key is pressed
{
elap_time(); // check time remaining
dv_pause(); // give up time slice
}
Page 40
GAP Communications GAPCDR
elap_time
-----------------------------------------------------------------
Purpose Computes elapsed time while waiting for keyboard
input.
void elap_time(void);
Type High Level
Description This function is used in loops that await a key-
board response. Prior to entering the loop, the
variable called temptime should be initialized with
the current time. Once inside the loop, this
function should be called to keep track of the
elapsed time. If there is no keyboard response
within 4 minutes, the user will be logged off.
Return Value None.
Example
time (&temptime); // start timer
while (!getakey()) // until a key is pressed
{
elap_time(); // check time remaining
dv_pause(); // give up time slice
}
Page 41
GAP Communications GAPCDR
empty
-----------------------------------------------------------------
Purpose Empties a string to all spaces.
void empty(char *str,short len);
str The string to be emptied
len Number of bytes to clear
Type High Level
Description Before using the string input routine, get_string,
the string must first be cleared to the maximum
number of bytes allowed to be input. Empty clears
the string to all spaces and adds a null byte at
the end. The null byte is not counted in the len
parameter.
Return Value None.
Example
char instr [11];
empty(instr,10); // empty the string
get_string(instr); // get up to 10 characters
// of input
Page 42
GAP Communications GAPCDR
fix_color
-----------------------------------------------------------------
Purpose Modify ANSI driver according to user's color.
void fix_color(void);
Type Low Level
Description The ANSI driver is self modifying, meaning that
depending upon the color preference of the user, it
will adjusts its code accordingly. This function is
called by init_ansi and should never need to be
called by the programmer directly unless the
programmer provides a menu choice whereby a caller
may toggle his/her color mode on and off. In such a
case, you would immediately need to call fix_color
so that the ANSI driver can adjusts itself. The
caller's color preference is stored in the variable
color where 0 means no color, and 1 means color.
Return Value None.
Example
show_mess("Toggle Color",NO,NO); // part of menu
empty(response,1); // clear string
get_string(response); // get response to menu
if (response[0] == 'C') // wants to toggle color
{
if (color)
color = 0
else
color = 1;
fix_color(); // fix up ANSI driver
}
Page 43
GAP Communications GAPCDR
gapputc
-----------------------------------------------------------------
Purpose Sends a single character to local and remote.
void gapputc(short ch);
ch Character to send
Type Low Level
Description This is one of the main output routines that is
used internally by GAPCDR. It is part of the ANSI
driver. It will send a single character to the
local screen and if a remote caller is on, will
send the character to the communications port as
well.
Return Value None.
Example gapputc('A'); // display a character
while ( (c = getakey()) == 0) // wait for keypress
dv_pause(); // give up time slice
gapputc(c); // display character
Page 44
GAP Communications GAPCDR
gapputs
-----------------------------------------------------------------
Purpose Sends a string of characters to local and remote.
void gapputs(char *str);
str String to send
Type Low Level
Description This is one of the main output routines that is
used internally by GAPCDR. It is part of the ANSI
driver. It will send a string of characters to the
local screen and if a remote caller is on, will
send the string to the communications port as well.
If a caller is in mono mode, the ANSI driver will
strip any ANSI sequences from the string. This
allows you to "colorize" your strings with ANSI
codes and not have to worry if the caller has his
color setting turned on.
This routine is much faster than show_mess (in
fact, this is the function that show_mess calls),
but it does not provide for ringing the bell or
automatically sending a carriage return and line
feed after the string. You can however embed these
characters into the string. It is suggested that
you not embed the bell character into the string
since the sysop may have the alarm toggled off and
may not appreciate the computer making noise when
he/she doesn't want it to.
Return Value None.
Example gapputs("This is a string of characters");
// this example embeds the CR/LF pair at the beginning
// and end of the string
gapputs("\r\nThis is a string\r\n");
Page 45
GAP Communications GAPCDR
getakey
-----------------------------------------------------------------
Purpose Gets one key responses
short getakey(void);
Type High Level
Description This is the main keyboard input routine. It is
called by get_string as well as any keyboard
polling loops. It checks the receive buffer as well
as the local keyboard for a key press. If one is
not found it returns 0. The character input is not
echoed. Since 99% of all keyboard input comes from
this routine, it checks for time remaining,
keyboard time-out, as well as special sysop
function keys. The timeleft variable is updated by
this routine. This is the variable you would
normally use in a prompt such as:
[20 mins left] Main Command :
Return Value ASCII code for the key pressed or 0.
Example c = getakey(); // get a character
Page 46
GAP Communications GAPCDR
getkeyc
-----------------------------------------------------------------
Purpose Gets keyboard character and scan code.
short getkeyc(void);
Type Low Level
Description This is the main keyboard input routine which is
called internally by getakey. It returns the
keyboard character or if the key struck was an
extended key, it will return a unique code. These
codes are defined in GAPSTRUC.H as F1, Home, etc.
This function always waits for a keypress so it
should not be called unless you know there is a key
waiting.
Return Value ASCII code for the key pressed or a unique code for
extended keys.
Example keyc = getkeyc(); // get a keyboard character
get_attr
-----------------------------------------------------------------
Purpose Retrieves the current screen color.
void get_attr(void);
Type Low Level
Description This function is used at the very start of a
program to "remember" the screen color. It stores
the color in a special location so that the screen
attributes can be restored by the DOS Window
routines. You do not need to call this routine if
you have no plans to use the DOS Window.
Return Value None. Attribute is stored in an internal location.
Example get_attr(); // Remember screen attributes
Page 47
GAP Communications GAPCDR
get_random
-----------------------------------------------------------------
Purpose Gets a random number.
short get_random(short low,short high);
low Lowest number acceptible
high Highest number acceptible
Type High Level
Description This routine is provided because it is much easier
to use and understand than the C library routine
(which drags in the floating point library).
Provide as parameters, two integers. The first
parameter is the lowest number you will accept as a
random number, and the second parameter is the
highest random number you will accept. The function
will return a random integer between the range
specified (low and high are included in the range
of numbers). It is not necessary to seed the random
number generator as this is done automatically for
you during program initialization.
Return Value A random number between range specified.
Example rndnum = get_random(1,10); // get a random num
Page 48
GAP Communications GAPCDR
get_string
-----------------------------------------------------------------
Purpose Gets a string of characters.
void get_string(char *string);
string Storage for input characters
Type High Level
Description This is the main input routine. It will get a
string from either the remote user or the local
keyboard. The string passed will be set to the
characters received. The length of the input string
is determined by the length of the string passed.
Before calling, you must initialize the passed
string with spaces. The number of spaces in the
string determines the number of characters allowed
to be input. If a user attempts to type more
characters than allowed, the cursor will not move
pass the end of the string. Input ends when the
Enter key is pressed.
To initialize the string, use the empty function.
WARNING : It is extremely important that the passed
string be initialized. Failure to set the string to
spaces, will cause unpredictable results!
This function does not return a new string con-
taining the keyboard input. Instead, it modifies
the string you pass to it in the parameter list.
The string will be stripped of any trailing spaces.
Get_string automatically uppercases the string. If
you wish to disable this feature, set the variable
noup to 1 just prior to calling the function, and
then set it back to 0 when the function returns.
Get_string will automatically check for keyboard
activity so it is not necessary for you to do so.
Return Value None
Example get_string(instr); // get a string
Page 49
GAP Communications GAPCDR
char instr [20];
// First initialize the string. In this case we will
// accept up to 10 characters
empty(instr,10); // initialize string
get_string(instr); // get string
init_ansi
-----------------------------------------------------------------
Purpose Initialize ANSI driver.
void init_ansi(void);
Type Low Level
Description This routine is called by init_door so it is not
necessary for you to call it again. It sets up the
ANSI driver so that it knows the sysop's default
color, the current cursor position, etc.
Return Value None.
Example init_ansi(); // Initialize ANSI driver
init_com
-----------------------------------------------------------------
Purpose To configure the communications port.
void init_com(void);
Type High Level
Description This function takes the information provided by
DOOR.SYS and makes a call to setport to set up the
communications port and receive buffer. It is
called internally by init_door. If there is an
error setting up the port, init_com will exit the
program.
Return Value None. Exits on Error.
Example init_com(); // Initialize com port
Page 50
GAP Communications GAPCDR
init_door
-----------------------------------------------------------------
Purpose Initializes the GAPCDR functions.
void init_door(void);
Type High Level
Description This routine must be called immediately after
calling read_cnf. It initializes the door, opens
and reads system files, initializes the com port,
initializes global variables and in general, makes
sure that all of the files required for operation
are present. If an error occurs while trying to
initialize, the function will display an error
message and end the program.
Return Value None. Exits on error.
Example
fp = read_cnf("DOOR.CNF"); // read cnf file
init_door(); // init the door
fclose(fp); // close configuration file
init_port
-----------------------------------------------------------------
Purpose Initialize port to baud, data, and parity.
init_port(short parity, short data);
parity 0 = None, 1 = Even
data 6,7,or 8 data bits
Type Low Level
Description Sets the communications port to the parity and data
bits passed as parameters. The baud rate is
contained in a global variabled called baud. The
port number (where COM 1 equals port 0) is
contained in a global variabled called port.
RETURN VALUE 0 = SUCCESSFUL, 1 = ERROR.
Example init_port(0,8) // Initialize to N,8,1
Page 51
GAP Communications GAPCDR
iscd
-----------------------------------------------------------------
Purpose Check for Carrier on the Communications Port.
short iscd(void);
Type Low Level
Description This function allows you to test the communications
port for a remote carrier signal. Note that carrier
checking is performed automatically by the
communications routines so it is not necessary for
you to explicitly check for carrier unless you have
a need to override the default actions taken.
Return Value Returns 0 if there is no carrier and 1 if there is
a carrier.
Example
if ( !iscd()) // is there a carrier?
leave(99); // nope, lets quit
leave
-----------------------------------------------------------------
Purpose Exits the program.
void leave(short code);
code Exit code to terminate with
Type High Level
Description When the program terminates, it must call this
function to end. This is the only proper exit from
the door. It is of vital importance to end your
program through this function so that the interrupt
service routines that are installed at door
beginning can be removed.
Return Value None.
Example leave(0); // Exit the program
Page 52
GAP Communications GAPCDR
lputc, lputs
-----------------------------------------------------------------
Purpose To display a character or string of characters on
the local screen.
void lputc(char ch);
ch Character to display
void lputs(char *str);
str String to display
Type Low Level
Description Like gapputc and gapputs, these functions display
either a single character or a string of
characters, however the characters are not
simultaneously sent to the communications port as
well. These functions override the color mode of
the caller and allow you to send ANSI color to the
local screen even if the caller does not have his
color flag turned on.
Return Value None.
Example lputs("This is a string"); // Send string
more
-----------------------------------------------------------------
Purpose Checks for a full screen and issues a More Prompt.
void more(void);
Type High Level
Description This is an internal routine that is called by the
character output functions. It issues a more prompt
if the number of lines displayed reaches the user's
page length.
Return Value None.
Page 53
GAP Communications GAPCDR
nl
-----------------------------------------------------------------
Purpose Sends a Carriage Return and Line Feed to local and
remote.
void nl(short lines);
lines Number of New Lines to send
Type High Level
Description To send a blank line, call this routine with the
number of blank lines you wish to send.
Return Value None
Example nl(2); // send two blank lines
no_carrier
-----------------------------------------------------------------
Purpose Used by the Communications routines.
void no_carrier(void);
Type High Level
Description Internal routine that is called when there is a
loss of carrier. Displays a message to the local
screen and then calls leave to terminate the
program. This function must not be removed from
GAPCDR. You may modify it to change the default
actions that are taken, but the communications
routines must have access to it if there is a loss
of carrier.
Return Value None.
Example
Page 54
GAP Communications GAPCDR
pagesysop
-----------------------------------------------------------------
Purpose Alerts sysop that user wants to chat.
void pagesysop(void);
Type High Level
Description Allows the programer to provide the user with a
Page Sysop command. The page lasts for 30 seconds
and can be aborted by typing CTRL-K. If the sysop's
page bell is on, the sysop's speaker will also
sound. To answer the page, the sysop should press
CTRL-F10.
Return Value None.
Example pagesysop(); // tell sysop
empty(response,1); // initialize string
get_string(response); // get a response
if (response[0] == 'P') // wants to chat
pagesysop(); // tell sysop
pause
-----------------------------------------------------------------
Purpose Sends a "Press [Any Key] To Continue" prompt.
void pause(void);
Type High Level
Description This function sends a pause prompt and waits for a
key press.
Return Value None.
Example pause(); // display pause prompt
Page 55
GAP Communications GAPCDR
putkey
-----------------------------------------------------------------
Purpose Used by chat routines to keep track of word
wrapping.
void putkey(short ch);
ch Character to send
Type High Level
Description This is the main output routine for the chat
functions. It keeps track of the current column,
and decides when it is time to wrap a word.
Return Value None.
Example
Page 56
GAP Communications GAPCDR
read_cnf
-----------------------------------------------------------------
Purpose Reads the door configuration file.
FILE *read_cnf(char *path);
path Full path and name of configuration file
Type High Level
Description Opens the configuration file for the current door.
Normally the passed parameter is the name of the
door with a .CNF extension (it is assumed that the
file is in the same directory as the door program).
If an error occurs, the program ends immediately.
WARNING : The first eight lines of this configura-
tion file belong to the GAPCDR interface module.
You are free to use the information, but the in-
formation contained in the first eight lines must
conform exactly to the following specifications.
The first line of this file is the full drive and
path to the BBS default directory. This is the
directory where the BBS created the DOOR.SYS file.
The second line is the name of the BBS. The third
line is the IRQ for the port, and the fourth line
is the Base Address for the port. If the sysop uses
Com Ports other than 1 or 2, then he must enter the
appropriate IRQ and BASE address so that GAPCDR can
properly open the port. If Com ports 1 or 2 are
used, then a 0 may be entered on both of these
lines. The fifth line is the Communications Port
Interface and must be either STANDARD, DIGIBOARD,
or INT14/EBIOS. The sixth line is the DigiBoard
Memory Window. The seventh line is the DigiBoard
I/O Port Address. The eighth line is the DigiBoard
Channel Number.
It is the responsibility of the door author to
describe the format of these eight lines to the end
user. If your door program requires no
configuration parameters of its own, you can simply
distribute a sample configuration file with these
eight lines already in it.
Page 57
GAP Communications GAPCDR
GAPCDR will not close this file after reading the
first four lines. It leaves the file open for the
programmer's use. Remember that you assign a FILE
pointer to the return value so that you may access
the file. If your door does require certain
configuration parameters, have your users place the
parameters in the file starting with line 9. If you
use a set up program, be sure that your set up
program writes the first eight lines as specified.
After you have called read_cnf and init_door, if
you have any configuration options in the
configuration file, you should use the stream input
routines to read those options. Then fclose the
file using the FILE pointer returned. Even if you
have no options to read, you must close the file.
WARNING : You must call this routine before using
any of the GAPCDR functions. After calling this
routine, you must call init_door.
Return Value FILE pointer.
Example
FILE *fp; // File pointer
fp = read_cnf("TOURIST.CNF"); // read cnf file
fclose(fp); // close the file
init_door(); // init the door
read_doorsys
-----------------------------------------------------------------
Purpose Reads the DOOR.SYS universal door interface file.
short read_doorsys(void);
Type High Level
Description Internal routine called by init_door. Reads the
DOOR.SYS file and initializes any global variables
that depend on the information in that file.
Return Value 0 = no error, 1 = error.
Example c = read_doorsys();
Page 58
GAP Communications GAPCDR
read_gapuser
-----------------------------------------------------------------
Purpose Reads the GAP Communications USERS.DAT file.
short read_gapuser(char *path);
path Full path and name of the USERS file
Type High Level
Description Reads the user record of the current user in the
GAP USERS.DAT file. The record is read into a
structure variable called gapuser. You must supply
the path and name to the base part of the User
file. GAP stores the name of the User file in the
GAPBBS.CNF file (which you must read yourself).
Read_gapuser will add the .DAT extension.
Return Value 0 = no error, 1 = error.
Example c = read_gapuser(userpath);
read_pcbsys
-----------------------------------------------------------------
Purpose Reads the PCBOARD.SYS file.
short read_pcbsys(void);
Type High Level
Description Reads the PCBOARD.SYS system file. The record is
read into a structure variable called pcbsys.
Return Value 0 = no error, 1 = error.
Example c = read_pcbsys();
Page 59
GAP Communications GAPCDR
read_pcbuser
-----------------------------------------------------------------
Purpose Reads the PCB USERS file.
short read_pcbuser(char *path);
path Full path and name of the USERS file
Type High Level
Description Reads the user record of the current user in the
PCB USERS file. The record is read into a structure
variable called pcbuser. You must supply the path
and name to the User file. PCB stores the path\name
of the User file in the PCBOARD.DAT file (which you
must read yourself).
Return Value 0 = no error, 1 = error.
Example c = read_pcbuser(userpath);
Page 60
GAP Communications GAPCDR
read_score
-----------------------------------------------------------------
Purpose Reads the score file and displays the results.
short read_score(char *datfile,char *message);
datfile Path and name of data file to read
message Message to display
Type High Level
Description This function will read the scoreboard data file
for your door (if any) and display the results. You
pass as parameters the name of the data file to
read, and a message to display at the top of the
scoreboard. The message could be something like
"Top 10 Players".
Return Value 0 = scores read, 1 = no scores to read.
Example read_score("TOURIST.DAT","Top 10 Tourists");
if (read_score("TOURIST.DAT","Top 10 Tourists"))
{
nl(1);
ansi(BWHITE);
show_mess("No one's made it Yet!",NO,YES);
}
Page 61
GAP Communications GAPCDR
reset_port
-----------------------------------------------------------------
Purpose Restores the Communications port.
void reset_port(void);
Type Low Level
Description This function must be called prior to exiting the
program. It restores the interrupt vector used by
the communications routines. It is called
internally by leave so it is not necessary for you
to explicitly invoke it.
Return Value None.
Example reset_port(); // Restore communications port
Page 62
GAP Communications GAPCDR
restore_screen
-----------------------------------------------------------------
Purpose Restores a previously saved portion of the screen.
void restore_screen(short topr, short topc,
short botr, short botc,
unsigned short memseg);
topr Top row of screen
topc Top left column of screen
botr Bottom row of screen
botc Bottom right column of screen
memseg Segment of buffer to save to
Type Low Level
Description This function allows you to restore a previously
saved portion of the screen. You supply the top row
and column and the bottom row and column co-
ordinates of the rectangle. All co-ordinates are 0
based. The memseg is the segment address of the
buffer that a previous call to save_screen saved
the video contents to.
Return Value None.
Example restore_screen(3,8,16,71,dseg);
Page 63
GAP Communications GAPCDR
rest_cbreak
-----------------------------------------------------------------
Purpose Restores the Ctrl-Break vector.
void rest_cbreak(void);
Type Low Level
Description This function must be called prior to exiting the
program. It restores the interrupt vector used by
the Ctrl-Break routine. It is called internally by
leave so it is not necessary for you to explicitly
invoke it.
Return Value None.
Example rest_cbreak(); // restore Ctrl-Break vector
rest_int10
-----------------------------------------------------------------
Purpose Restores the interrupt 10 (BIOS) vector.
void rest_int10(void);
Type Low Level
Description When setting up an interrupt 10 BIOS trap to
protect a DOS Window, this function must be called
when it is no longer necessary to protect a portion
of the screen.
Return Value None.
Example See the example for set_cord.
Page 64
GAP Communications GAPCDR
rts
-----------------------------------------------------------------
Purpose Toggle the RTS line on and off.
void rts(short how)
how 0 = Turn RTS off.
1 = Turn RTS on
Type Low Level
Description This routine is used to turn the RTS line of the
communications port on or off. Turning RTS off
(providing the modem supports hardware handshaking)
tells the modem to stop sending data to the
computer. It is typically toggled off while writing
a buffer of data to a disk.
Return Value None.
Example rts(0); // Turn RTS off
rxempty
-----------------------------------------------------------------
Purpose To check if there are any characters in the receive
buffer.
short rxempty(void);
Type Low Level
Description This function checks the communications receive
buffer to see if there are any characters waiting
to be read.
Return Value Returns 1 if buffer is empty, 0 if there are
characters waiting to be read.
Example
while (rxempty()) // nothing happening
dv_pause(); // give up time slice
Page 65
GAP Communications GAPCDR
save_screen
-----------------------------------------------------------------
Purpose Saves a portion of the screen.
void save_screen(short topr, short topc,
short botr, short botc,
unsigned short memseg);
topr Top row of screen
topc Top left column of screen
botr Bottom row of screen
botc Bottom right column of screen
memseg Segment of buffer to save to
Type Low Level
Description This function allows you to save a rectangular
portion of the screen. You supply the top row and
column and the bottom row and column co-ordinates
of the rectangle. All co-ordinates are 0 based. The
memseg is the segment address of a buffer to save
the video contents to and assumes your buffer was
allocated by DOS (i.e., the offset portion of the
buffer begins at 0).
Return Value None.
Example
unsigned short dseg;
dos_allocatemem(114,&dseg); // get some memory
save_screen(3,8,16,71,dseg); // save contents of video
Page 66
GAP Communications GAPCDR
setport
-----------------------------------------------------------------
Purpose Initialize the Communications Port.
short set_port(short bufsize, short irq,
short base);
bufsize Size of Receive buffer
irq Port IRQ to use
base Port Base Address to use
Type Low Level
Description This is the port initialization routine that is
called by init_com. Bufsize is the size of the
receive buffer to set up. Set_port will allocate
memory based upon this size. Typical values are
from 1200 to 4096 bytes. Note that the bufsize
argument is ignored when using the Borland
compiler. This is because Borland does not provide
a memory allocation routine that allocates memory
in the near heap (irregardless of memory model).
For Borland, the bufsize is fixed at 2048 bytes.
IRQ is the Interrupt Request number to use for the
port and Base Address is the address where the port
is located. The Port number is a global variable
that is set when reading DOOR.SYS. Ports start with
0, where 0 equals COM 1, 1 equals COM 2, etc. For
COM 1 and COM 2, you may simply pass 0 as the IRQ
and Base address since the defaults for these ports
will be used.
Return Value 0 = successful, 1 = error encountered.
Example
// set up the port with a buffer size of 2k, using COM 1
port = 0;
if (setport(2048, 0, 0))
exit(1);
Page 67
GAP Communications GAPCDR
set_attr
-----------------------------------------------------------------
Purpose Sets the video color attributes.
void set_attr(unsigned char forg, unsigned char
back);
forg Foreground Color (0-15)
back Background Color (0-7)
Type Low Level
Description This function is used just prior to invoking a DOS
Window so that the window colors can be set.
Return Value None.
Example See the example for set_cord.
set_cbreak
-----------------------------------------------------------------
Purpose Initializes the Ctrl-Break vector.
void set_cbreak(void);
Type Low Level
Description To trap Ctrl-C and Ctrl-Break, this function should
be called to set up an interrupt service routine to
trap these two keys. It is imperitive that the
program not exit before calling rest_cbreak so that
the interrupt vector can be restored. Leave does
this for you automatically.
Return Value None.
Example set_cbreak(); // set up Ctrl-Break ISR
Page 68
GAP Communications GAPCDR
set_cord
-----------------------------------------------------------------
Purpose Set up a DOS Window.
void set_cord(unsigned char topr,
unsigned char topc,
unsigned char botr,
unsigned char botc);
topr Top left row
topc Top left column
botr Bottom row
botc Bottom right column
Type Low Level
Description This function sets the window co-ordinates for a
DOS Window. Using this function in combination with
set_int10 allows you to set up a window into which
all local screen output will be directed. Topr and
topc are the top left corner of the window and botr
and botc are the bottom right corner of the window.
All co-ordinates are 0 based.
Return Value None.
Example
_dos_allocmem(114,&dseg); // get some memory
save_screen(3,8,16,71,dseg); // save a part of screen
set_int10(); // set up BIOS trap
set_cord(4,9,15,70); // tell it what to protect
set_attr(14,1); // Yellow on Blue
cls_all(); // clear the window
system("COMMAND"); // go to DOS
rest_int10(); // restore vector
restore_screen(3,8,16,71,dseg); // restore screen
_dos_freemem(dseg); // free memory
Page 69
GAP Communications GAPCDR
set_int10
-----------------------------------------------------------------
Purpose Set up an interrupt 10 (BIOS) trapper.
void set_int10(void);
Type Low Level
Description This function intercepts the Interrupt 10 vector so
that it can trap calls to the BIOS video output
routines. It is used in conjunction with set_cord
to set up a portion of the screen into which all
video output through the BIOS will be directed. If
a console driver other than CON or ANSI.SYS is used
that writes directly to the screen, this function
will not work.
Return Value None.
Example See the example for set_cord.
set_status
-----------------------------------------------------------------
Purpose Displays and updates the sysop status line.
void set_status(short how);
how 0 = set the status line
1 = update the status line
4 = show other user stats
Type High Level
Description Displays or updates the sysop status line.
Return Value None.
Example set_status(0); // display status line
Page 70
GAP Communications GAPCDR
show_file
-----------------------------------------------------------------
Purpose Displays a text file.
void show_file(char *filename);
filename Full path and name of file to display
Type High Level
Description Many door programs have welcome, news, exit, help
and other files to show to the user at various
points in the program. This is the function that
allows you to do that. To display a file to the
user, call the function with the full
drive\path\filename of the file to display.
If you have color and non-color versions of files
pass the name of the non-color version as this
function will automatically append a "G" to the
filename if the user is in color mode. In fact,
this function will always try to find a file with a
"G" appended to the end of the name (if the user is
in color mode) before it looks for the actual file
by the name you specified. If you pass "WELCOMEG"
to this function and the user is in color mode, it
will first try to find a file with the name of
"WELCOMEGG".
Pressing CTRL-K or CTRL-X will abort any file
display.
REMEMBER : If you have both color and non-color
versions of the same files, pass the name of the
non-color version. Also, the actual disk files must
be named in such a way that they have no file
extension and the color version ends with a "G".
Return Value None.
Example show_file("WELCOME"); // display welcome file
Page 71
GAP Communications GAPCDR
show_mess
-----------------------------------------------------------------
Purpose Displays a message.
void show_mess(char *message,short bell,
short newline);
message Message to display.
bell YES or NO to ring the bell.
newline YES or NO to issue a CR/LF after
message.
Type High Level
Description This is the main string output function for GAPCDR.
Under most circumstances, this is the only function
that you would call to display output to the user.
Return Value None
Example show_mess("This is a message!",NO,YES);
// the first show_mess displays the string and leaves the
// cursor on the same line. The second displays the
// string, rings the remote user's bell, and drops the
// cursor to the next line.
nl(1);
show_mess("Are you ready? (Y/N) : ",NO,NO);
empty(response,3);
get_string(response);
if (response[0] == 'Y')
// begin whatever it is you want to begin
else
show_mess("Too Bad!",YES,YES);
Page 72
GAP Communications GAPCDR
timer
-----------------------------------------------------------------
Purpose Pauses for the number of "ticks" specified.
void timer(short ticks);
ticks Number of timer ticks to pause.
Type High Level
Description This function allows you to pause all processing
for the specified number of ticks. It is in-
sensitive to processor speed.
The function simply delays the number of "ticks"
indicated by the passed parameter. Each tick is
1/18 of a second (or 55 miliseconds).
Return Value None.
Example timer(18); // pause for 1 second
Page 73
GAP Communications GAPCDR
time_credit
-----------------------------------------------------------------
Purpose Issues timecredits to user.
void time_credit(short flag);
flag 1 = start timer
0 = end timer
Type High Level
Description This is basically an internal routine called by
chat and sysop shell to DOS so that the user is not
penalized for time used. It updates a global
variable called timecredit. Timecredit is used in
the calculations that determine the user's time
remaining.
If you wish to use this feature in your own rou-
tines, prior to entering your routine, call
time_credit with a 1 and it will start the timer.
When your routine is finished, call time_credit
with a 0 and the timer will stop. The variable
timecredit will be updated with the elapsed time.
Return Value None.
Example time_credit(1); // start the timer
time_credit(1); // start the timer
do_chat(); // chat with user
time_credit(0); // stop the timer
Page 74
GAP Communications GAPCDR
time_left
-----------------------------------------------------------------
Purpose To compute the user's time remaining.
void time_left(void);
Type High Level
Description This is the function that is called by the input
and output routines to compute the user's time
remaining. It is not necessary for the programmer
to call this routine directly.
A global variable called timeleft will be updated
with each call. This variable may be used in
prompts that display the user's remaining time.
As long as all input/output is performed thru calls
to the GAPCDR library, the timeleft variable will
always be current.
Return Value None.
Example time_left(); // calculate time remaining
trim
-----------------------------------------------------------------
Purpose Trims spaces from the end of NULL terminated
strings.
char *trim(char *string);
string String containing trailing spaces
Type High Level
Description This function will remove any spaces from the end
of a string. It modifies the passed string.
Return Value Pointer to the string without the spaces.
Example trim(username); // get rid of spaces
Page 75
GAP Communications GAPCDR
update_clock
-----------------------------------------------------------------
Purpose Updates the status line clock.
void update_clock(void);
Type High Level
Description Internal routine to update the status line clock.
Return Value None.
Example
wrap_word
-----------------------------------------------------------------
Purpose To wrap a word during sysop chats.
void wrap_word(void);
Type Low Level
Description Internal function called by putkey to wrap words.
Return Value None.
Example
Page 76
GAP Communications GAPCDR
write_gapuser
-----------------------------------------------------------------
Purpose Updates the user record in GAP's USERS.DAT file.
short write_gapuser(char *path);
path Full path and name of Users File
Type High Level
Description This function allows you to update any variables in
the GAP USERS.DAT file for the current user. You
must first read the user record before you can
write to it.
You must pass the path and name of the Users file.
The name is obtained by reading GAPBBS.CNF.
Write_gapuser will add the .DAT extension.
WARNING : The GAP USERS.DAT file contains strings
that are fully padded with spaces. If you modify
any of these strings, you MUST make sure that the
string is fully padded with spaces and that the
NULL character is placed in the last string posi-
tion.
WARNING : The indexes for the user file consists of
the user's last name and first name, user's level,
and user's handle. Do not under any circumstances
modify either of these four fields. Doing so will
cause corruption of the Index file.
Return Value 0 = no error, 1 = error.
Example c = write_gapuser(userpath);
// allow user to change city and state
c = read_gapuser(userpath);
if (c == 0)
{
show_mess("Enter City/State : ",NO,NO);
empty(city,29); // clear string
get_string(city); // get response
Page 77
GAP Communications GAPCDR
if (city[0] != 0) // if something entered
{
strcpy(user.city,city); // copy it
pad(user.city,29); // pad it with spaces
c = write_gapuser(userpath); // update user record
if (c == 0)
show_mess("Saved new City",NO,YES);
}
}
write_pcbsys
-----------------------------------------------------------------
Purpose Updates the PCBOARD.SYS file.
short write_pcbsys(void);
Type High Level
Description This function allows the programmer to update the
PCBOARD.SYS File. You must first read the file
before you write to it and you should not use this
function unless you know that your program is
running with PCB as the host system.
Return Value 0 = no error, 1 = error.
Example c = write_pcbsys() // write the file
Page 78
GAP Communications GAPCDR
write_pcbuser
-----------------------------------------------------------------
Purpose Updates the PCB USERS file.
short write_pcbuser(char *path);
path Full path and name to the Users file
Type High Level
Description This function allows the programmer to update the
PCB USERS File. Do not use unless you know your
program is running under a PCB host system. You
must first read the user record before you can
write to it.
You must pass the path and name of the Users file.
The name is obtained by reading PCBOARD.DAT.
Return Value 0 = no error, 1 = error.
Example c = write_pcbuser(); // write the file
Page 79
GAP Communications GAPCDR
write_score
-----------------------------------------------------------------
Purpose Creates and maintains a scoreboard.
void write_score(char *filename,long score);
filename Path and name of data file to write to
score Score to write
Type High Level
Description This function will create and maintain a scoreboard
of the top ten players. You pass it two parameters.
The first is a string containing the name of the
data file to create/maintain. The second is a long
unsigned integer containing the score to write. The
user's name and the current date are already known.
If the sysop is in the door at the time, the
function will simply return and not write a score.
The scores will automatically be sorted in
decreasing order by the highest score. If you wish
to use this routine but your points are kept as
shorts instead of longs, simply cast the second
parameter to an unsigned long.
Return Value None.
Example
short points;
points = 1000;
write_score("TOURIST.DAT,(unsigned long) points);
Page 80
GAP Communications GAPCDR
Index
Access1 27, 29
Alarm 23
Ansi 27, 29
Ansi driver
color 7, 43, 45, 53
external 17, 20
initializing 11, 50
internal 7, 12, 43
ANSI variables 8, 22
Anystring 26
Backspace 26, 27, 30
Base address 9, 15, 25, 57, 67
Base_add 25, 57, 67
Batch file 16
Baud 18, 19, 20, 23, 51
Baud rate 6, 18, 19, 20, 23, 51, 67
BBS
default directory 26, 57
name 26
system files 14, 26, 59, 60, 77, 78, 79
Bbs_dir 26, 57
Bell 23, 72
Birthday 26
Board_name 26
Bphone 24
BS 26
Business phone number 24
Caller alarm 23
Caller's birth date 26
Carriage return 26
Carrier 18, 19, 52, 54
Characters
sending to com port 27, 34
sending to local & remote 27, 44
sending to local screen 27, 53
Chat 17, 25, 37, 56
Chatting with user 25
City 24
Ckeypress 27, 30
Clear_scrn 27, 31
Clockon 25, 76
Clr_buf 27, 31
Cls 27, 31, 32
Cls_all 27, 32
Color 7, 20, 23, 25, 29, 43, 45, 47, 53, 68
Page 81
GAP Communications GAPCDR
Column 25
Comgetc 19, 27, 33
Comgetd 19, 27, 33
Communications
advanced applications 18
base address 9, 15, 25, 57, 67
baud rates 6, 18, 19, 20, 23, 67
carrier 18, 19, 52, 54
configuration file 9
DTR 20
FIFO buffers 6
Functions
clr_buf 27, 31
comgetc 27, 33
comgetd 27, 33
computb 27, 34
computc 27, 34
computs 27, 35
dtr 27, 38
init_port 19, 20, 27, 51
iscd 27, 52
no_carrier 27, 54
reset_port 19, 28, 62
rts 28, 65
rxempty 28, 65
setport 19, 28, 67
initializing 19, 50, 51, 67
input 19, 33, 65
interrupt 11, 19, 52, 62
IRQ 9, 15, 25, 57, 67
output 20, 34, 35
port 11, 12, 18, 23, 57, 67
Compilers
compiling & linking 12
cputs 12
floating point 8, 13, 48
function calling 13
goto 13
header files 8, 47
printf 12
Quick C 13
supported 8
Compiling 12
Computb 27, 34
Computc 20, 27, 34
Computs 20, 27, 35
Configuration file 9, 11, 15, 16, 57
format 9, 15
Page 82
GAP Communications GAPCDR
Control characters 8
editor 8
Cputs 12
CRLF 26, 45
Ctrl-Break handler 11, 64, 68
Curbytes 24
Curfiles 23
Current display color 25
Current download bytes 24
Current files downloaded 23
Current time 25
Cursoff 27, 35
Curson 27, 36
Cursor 27, 35, 36
Curtime 26
Date user's subscription expires 24
Default color 23
Delaying 73
DESQview 18, 27, 30, 33, 39, 40, 41
Dflt_color 23
Display clock 25
Display color 25
Distribution files 7
Do_chat 27, 37
DOOR.SYS 7, 9, 12, 14, 26, 58
Universal format 7
Variables 23
Doors 16
Doors opened 24
Doors_opened 24
DOS shell 17, 20
DOS Window 20, 47, 63, 64, 66, 68, 69, 70
Downbytes 24
Download bytes 24
Downloads 24
DSZ 20
DTR 20, 27, 38
Dv_here 18, 27, 39
Dv_pause 18, 27, 30, 40, 41
Editor 8
control characters 8
Elap_time 27, 41
Empty 27, 42, 49
Endview 25
Event_time 24
Expert 23
Files
checking for existence of 27, 29
Page 83
GAP Communications GAPCDR
configuration 9, 15
displaying 25, 71
DOOR.SYS 7, 9, 14
GAPCDR.H 8, 11
GAPSTRUC.H 8
PCBOARD.SYS 14
First name 24
Fix_color 27, 43
Flag 25
Floating point 8, 13, 48
Fname 24
Full name 24
Function calling 13
Function keys 17
Functions
access1 27, 29
ansi 29
backspace 30
ckeypress 30
clear_scrn 31
clr_buf 31
cls 31, 32
cls_all 32
comgetc 19, 33
comgetd 19, 33
computb 34
computc 20, 34
computs 20, 35
cursoff 35
curson 36
do_chat 37
DOS Window 20
dtr 38
dv_here 18, 39
dv_pause 18, 40
elap_time 41
empty 42, 49
fix_color 43
gapputc 44
gapputs 45
get_attr 20, 47
get_random 48
get_string 42, 49
getakey 46
getkeyc 47
init_ansi 50
init_com 50
init_door 10, 11, 51
Page 84
GAP Communications GAPCDR
init_port 19, 20, 51
iscd 52
leave 11, 52
lputc 53
lputs 53
more 53
nl 54
no_carrier 18, 54
pagesysop 55
pause 55
putkey 56
read_cnf 9, 10, 11, 57
read_doorsys 58
read_gapuser 12, 59
read_pcbsys 12, 59
read_pcbuser 60
read_score 61
reset_port 19, 62
rest_cbreak 64
rest_int10 64
restore_screen 63
rts 65
rxempty 65
save_screen 66
set_attr 68
set_cbreak 68
set_cord 69
set_int10 70
set_port 19
set_status 70
setport 67
show_file 71
show_mess 45, 72
time_credit 74
time_left 75
timer 18, 73
trim 75
update_clock 76
wrap_word 76
write_gapuser 77
write_pcbsys 78
write_pcbuser 79
write_score 80
GAPCDR.H 11
Gapputc 27, 44
Gapputs 27, 45
GAPSTRUC.H 8, 47
Gendir 26
Page 85
GAP Communications GAPCDR
Get_attr 20, 27, 47
Get_random 27, 48
Get_string 27, 42, 49
Getakey 27, 46
Getkeyc 27, 47
Gotdv 18
Goto 13
Handle 24
Header files
GAPCDR.H 8, 11
GAPSTRUC.H 8, 47
Home phone number 24
Hphone 24
Init_ansi 27, 50
Init_com 27, 50
Init_door 10, 11, 27, 51
Init_port 19, 20, 27, 51
Initializing
ANSI driver 11, 43, 50
interrupt handlers 11, 67
program 11, 47, 50, 51, 57, 58, 67, 68
strings 27, 42, 49
Input
from com port 19, 27, 33, 65
from local & remote 27, 30, 40, 46, 49
from local keyboard 27, 47
Instatus 25
Interrupt handlers
BIOS 64, 70
communications 19, 52, 62
CTRL-Break 11, 52, 64, 68
IRQ 9, 15, 25, 57, 67
Iscd 27, 52
Keyboard 30, 40, 46, 47, 49
timeout 30, 49
Last date user was on 24
Last name 24
Last new files scan 24
Last_new 24
Lastdate 24
Leave 11, 27, 52
Level 23
Line feed 26
Lines 25, 53, 54
Linking 12
Lname 24
Local 18, 23
Functions
Page 86
GAP Communications GAPCDR
cls 27, 32
cls_all 27, 32
cursoff 27, 35
curson 27, 36
getkeyc 27, 47
lputc 27, 53
lputs 27, 53
Local mode 12, 18
Lowercase characters 25, 49
Lputc 27, 53
Lputs 27, 53
Maindir 26
Make_sound 27
Maxbytes 24
Maxfiles 23
Maximum bytes available 24
Maximum files available 23
Mesleft 24
Messages left 24
Minsleft 23
Minutes left at door start 23
More prompt 25, 27, 53
Multi 12, 23
Multi user 12, 16, 29
Name of the BBS 26
NL 27, 54, 72
No clock 25
No_carrier 18, 19, 27, 54
Node 23
Node number 23
Non Stop mode 25
Normal 25
Noup 25, 49
Novice 23
NS 25, 53
Number of downloads 24
Number of times on 24
Output
to com port 20, 27, 34, 35
to local & remote 27, 28, 44, 45, 72
to local screen 27, 53
Page 23
Page bell 17, 23, 55
Page length 23, 53
Pagesysop 27, 55
Parity 23
Pascal
function calling 13
Page 87
GAP Communications GAPCDR
Password 24
Path to DOOR.SYS 26
Pause 27, 55
Pausing 73
PCBOARD.SYS 14
PKUNZIP 20
Port 18, 19, 23, 57, 67
Printer 23
Printf 12
Prompts
more 53
pause 55
Putkey 27, 56
Quick C 13
Random number generator 11, 27, 48
Read_cnf 9, 10, 11, 27, 57
Read_doorsys 28, 58
Read_gapuser 12, 28, 59
Read_pcbsys 12, 28, 59
Read_pcbuser 28, 60
Read_score 28, 61
Realcredit 23
Receive buffer 30, 31, 33, 65, 67
Recnum 24
Redisplay 25
Remote user 23
Remote user's bps rate 23
Reset_port 19, 28, 62
Rest_cbreak 28, 64
Rest_int10 28, 64
Restore_screen 28, 63
Rts 28, 65
Rxempty 28, 65
Save_screen 28, 66
Scan codes 47
Scoreboard 61, 80
Screen 23, 63, 66
clearing 31, 32
color 47, 53, 68
cursor 35, 36
full 53
Set_attr 28, 68
Set_cbreak 28, 68
Set_cord 28, 69
Set_int10 28, 70
Set_status 28, 70
Setport 19, 28, 67
Shell to DOS 17
Page 88
GAP Communications GAPCDR
Show_file 28, 71
Show_mess 28, 45, 72
Single user 12, 23
Starttime 25
Status line
displaying 17, 25, 70
protected 17
Strings
initializing 27, 42, 49
receiving from local & remote 27, 42, 49
removing spaces from 75
sending to com port 27, 35
sending to local & remote 27, 45, 72
sending to local screen 27, 53
Strtime 26
Structures 26
Subscrip 24
Sysname 26
Sysop
batch file 16
function keys 17
functions 14, 17
setup 14
Sysop's name 26
System files 14, 59, 60, 77, 78, 79
Temptime 25
Time 25
Time credits 23, 74
Time door opened 25
Time slice 18, 30, 33, 39, 40, 41
Time user has left 25, 41, 46, 75
Time_credit 28, 74
Time_left 28, 75
Timecredit 14, 25
Timeleft 25, 30, 46, 75
Timenow 25
Timeout 30
Timer 18, 28, 73
Timeson 24
Total uploads 24
Trim 28, 75
Twit 17
Upbytes 24
Update_clock 28, 76
Updating status line 25
Upload bytes 24
Uploads 24
Uppercase characters 25, 49
Page 89
GAP Communications GAPCDR
Usemore1 25
User Record 26
User's birth date 26
User's business phone 24
User's first name 24
User's full name 24
User's Handle 24
User's home phone 24
User's home town 24
User's last name 24
User's password 24
User's record number 24
User's security level 23
Userbaud 23
Username 24
Variables
ANSI 8, 22
Defines
NO 22
YES 22
DOOR.SYS
alarm 23
baud 18, 23
bell 23
bphone 24
city 24
color 23
curbytes 24
curfiles 23
dflt_color 23
doors_open 24
downbytes 24
downloads 24
event_time 24
expert 23
fname 24
handle 24
hphone 24
last_new 24
lastdate 24
level 23
lname 24
local 18, 23
maxbytes 24
maxfiles 23
mesleft 24
minsleft 23
multi 12, 23
Page 90
GAP Communications GAPCDR
node 23
page 23
parity 23
password 24
port 18, 19, 23
printer 23
realcredit 23
recnum 24
screen 23
subscrip 24
timeson 24
upbytes 24
uploads 24
userbaud 23
username 24
Global
anystring 26
base_add 25
bbs_dir 26
birthday 26
board_name 26
BS 26
chat 25
clockon 25
column 25
CRLF 26, 45
curtime 26
endview 25
flag 25
gendir 26
gotdv 18
instatus 25
IRQ 25
lines 25
maindir 26
normal 25
noup 25, 49
NS 25
redisplay 25
starttime 25
strtime 26
sysname 26
temptime 25
timecredit 14, 25
timeleft 25
timenow 25
usemore1 25
view 25
Page 91
GAP Communications GAPCDR
wordwrap 25
Structures
pcbsys 26
pcbuser 26
user 26
View 25
Window 20, 63, 64, 66, 68, 69, 70
Wordwrap 25, 56, 76
Wrap_word 28, 76
Write_gapuser 28, 77
Write_pcbsys 28, 78
Write_pcbuser 28, 79
Write_score 28, 80
Page 92
